                                   Manual of
                         RISC OS Inkjet Printer Dumper

                          Created 30.12.2002 T. Milius
                          Changed 14.09.2004 T. Milius

     ----------------------------------------------------------------------

                                    Content

    1. Overview
    2. Remarks
    3. Installation
         1. Supported printers
         2. Calibration
    4. Motivation
    5. Copyright
    6. Contact
    7. Useful links for making an own PDF
    8. History
         1. Version 1.00
         2. Version 1.01
         3. Version 2.07
    9. Future
   10. Technical details
         1. Printer control string cellar stack calculator
              1. Commands
              2. Addresses of Variables
              3. Programming example
         2. Printer individual calibration file
              1. The "Dummy for page size" mode
         3. External calibration file
         4. Ditherinfo file

                                  1. Overview

   The program consists of a printer dumper and a calibration program. The
   printer dumper has been designed for a usage with a lot of inkjet printers
   und can handle up to 10 colour cartridges.

   The dumper also allows you to print directly or dithered into a sprite
   file. Pages are stored as separate Sprites inside that file.

   The program is Freeware. See the Copyright-Section for more details.

                                   2. Remarks

   The dumper has been only tested with the EPSON Stylus Color 580 and the
   EPSON Stylus Photo 700 by myself. It can be also modified for usage with
   other printers. E.g. Martin Hodgson developed a PDF for the EPSON Stylus
   Photo 870.

   Usage and modification is done entirely on your own risc. If ink is
   squirting into your room e.g. on the wall paper, Aliens are attacking your
   house suddenly just after or while using the dumper I am taking no
   responsibility on it.

   Note that the dumper only generates sequences for a generating a printout
   on a printer. Other features like showing of remaining ink capacity, error
   descriptions and changing the ink catridges are not controlled by it. E.g.
   I must warn you about using an EPSON Stylus Color 580 if you are only
   owner of a RISC OS machine and not also of a PC. Changing the ink
   cartridges requires undocumented control sequences and so you can't change
   the cartridges under RISC OS or LINUX but only with the original PC
   software.

   Martin Hodgson was so pleased to write PDFs for other printers than the
   580 and to act as beta tester for my dumper. Please contact him if you
   want to use my driver with other EPSON-printers.

   Thanks must be also given to Robin Watts and Justin Fletcher for writing
   cmunge and to Daniel Ellis. Through that information I found out how to
   write the assembler adapter for C for 26-Bit RISC OS.

                                3. Installation

   Simply copy the "!PDPEICal" application somewhere onto your disc.
   Alternatively you can run it directly. It is not necassary for operation
   of the dumper only for installation and calibration if required.

   Run "!PDPEICal". If you are having an older incompatible version of
   "PDumperEI" already installed (like 1.x) this version will be removed and
   placed into a special temporary directory which will be shown
   automatically. You will see the application on the right side of the icon
   bar afterwards and a directory will be opened showing the available PDFs
   delivered with this application. At that moment the dumper has been
   already installed. However the calibration file must be still installed.
   To do so load an according PDF of your choice and activate it as the
   actual active printer. Take care that the selected printer is one which is
   handled by "PDumperEI".

   Then click on "!PDPEICal" on the icon bar. If there is an according
   calibration file for your printer avaliable this will be installed now.
   You will be informed about this by a message. If an according calibration
   file is already existing or if no file can be found the calibration window
   will alert and also a directory with available calibration files will be
   shown. Inside the calibration window there is a field where you can alter
   your calibration file from an existing one. You can therefore drag
   arbitrary calibration files on the window. When changing the field a
   button will be activated which must be pressed to use the entered file as
   new calibration file for your printer. If you want only to change the
   calibration file or to cancel the calibration process you can close the
   window else you will enter the calibration. You need not to fill the
   calibration file field. You can leave it blank if you want to calibrate
   entirely from scratch.

3.1. Supported printers

   For the following printers there is a PDF availabe for usage with
   PDumperEI in the moment.

   +------------------------------------------------------------------------+
   |Manufacturer| Type |          Description           | How to  |Developed|
   |            |      |                                | get it  |   by    |
   |------------+------+--------------------------------+---------+---------|
   |            |      |All Sprites are using 180/180   |         |         |
   |            |      |dpi resolution. Available       |         |         |
   |            |      |graphic modes are:              |         |         |
   |            |      |                                |         |         |
   |            |      |  * Dithered Black/White (1 Bit)|         |         |
   |            |      |  * Dithered colour (4 Bit)     |         |         |
   |            |      |  * Dithered colour (8 Bit)     |         |         |
   |            |      |  * Dithered Grey (2 Bit)       |         |         |
   |            |      |  * Dithered Grey (4 Bit)       |Supplied |         |
   |RISC OS     |Sprite|  * Dithered Grey (8 Bit)       |with the |Thomas   |
   |            |      |  * Direct (32 Bit)             |dumper   |Milius   |
   |            |      |                                |         |         |
   |            |      |Used calibrations:              |         |         |
   |            |      |                                |         |         |
   |            |      |  * 0 - Black/White             |         |         |
   |            |      |  * 1 - 4 Greys                 |         |         |
   |            |      |  * 2 - 16 Greys                |         |         |
   |            |      |  * 3 - 256 Greys               |         |         |
   |            |      |  * 4 - 16 Colours              |         |         |
   |            |      |  * 5 - 256 Colours             |         |         |
   |------------+------+--------------------------------+---------+---------|
   |            |Stylus|                                |Use      |         |
   |EPSON       |Color |                                |Stylus   |         |
   |            |480   |                                |Color 580|         |
   |            |      |                                |driver   |         |
   |------------+------+--------------------------------+---------+---------|
   |            |      |Available graphic modes:        |         |         |
   |            |      |                                |         |         |
   |            |      |  * 120/360 dpi 4 colour mode   |         |         |
   |            |      |    (15 nozzles)                |         |         |
   |            |      |  * 360/360 dpi 4 colour mode   |         |         |
   |            |      |    (15 nozzles)                |         |         |
   |            |      |  * 120/360 dpi Grey mode (48   |         |         |
   |            |      |    nozzles)                    |         |         |
   |            |      |  * 360/360 dpi Grey mode (48   |         |         |
   |            |      |    nozzles)                    |         |         |
   |            |      |  * 360/360 dpi colour dithered |         |         |
   |            |      |    Sprite output for preview   |         |         |
   |            |      |    purposes                    |         |         |
   |            |      |  * Page size mode              |         |         |
   |            |      |                                |         |         |
   |            |Stylus|Used calibrations:              |Supplied |Thomas   |
   |EPSON       |Color |                                |with the |Milius   |
   |            |580   |  * 0 - Colour normal paper     |dumper   |         |
   |            |      |  * 1 - Colour photo paper      |         |         |
   |            |      |  * 2 - Grey normal paper       |         |         |
   |            |      |  * 3 - Grey photo paper        |         |         |
   |            |      |                                |         |         |
   |            |      |Available Text modes:           |         |         |
   |            |      |                                |         |         |
   |            |      |  * No highlights               |         |         |
   |            |      |                                |         |         |
   |            |      |Pattern translation not         |         |         |
   |            |      |implemented. The text mode of   |         |         |
   |            |      |the Stylus Colour 580 is very   |         |         |
   |            |      |poor.                           |         |         |
   |            |      |Colours/Italic/Bold/Different   |         |         |
   |            |      |letter sizes etc. are not       |         |         |
   |            |      |available.                      |         |         |
   |------------+------+--------------------------------+---------+---------|
   |            |      |                                |Use      |         |
   |EPSON       |C20   |                                |Stylus   |         |
   |            |      |                                |Color 580|         |
   |            |      |                                |driver   |         |
   |------------+------+--------------------------------+---------+---------|
   |            |      |                                |Use      |         |
   |EPSON       |C40   |                                |Stylus   |         |
   |            |      |                                |Color 580|         |
   |            |      |                                |driver   |         |
   |------------+------+--------------------------------+---------+---------|
   |            |      |                                |Use      |         |
   |EPSON       |Stylus|                                |Stylus   |         |
   |            |Photo |                                |Photo 700|         |
   |            |      |                                |driver   |         |
   |------------+------+--------------------------------+---------+---------|
   |            |      |                                |Use      |         |
   |            |      |                                |Stylus   |         |
   |            |Stylus|                                |Photo 700|         |
   |EPSON       |Photo |                                |driver.  |         |
   |            |EX    |                                |Add large|         |
   |            |      |                                |page     |         |
   |            |      |                                |sizes.   |         |
   |------------+------+--------------------------------+---------+---------|
   |            |      |Available graphic modes:        |         |         |
   |            |      |                                |         |         |
   |            |      |  * 360/360 dpi 6 colour mode   |         |         |
   |            |      |    (24 nozzles)                |         |         |
   |            |      |  * 360/360 dpi Grey (24        |         |         |
   |            |      |    nozzles)                    |         |         |
   |            |      |  * 360/360 dpi colour dithered |         |         |
   |            |      |    Sprite output for preview   |         |         |
   |            |      |    purposes                    |         |         |
   |            |      |  * Page size mode              |         |         |
   |            |      |                                |         |         |
   |            |Stylus|Used calibrations:              |Supplied |Thomas   |
   |EPSON       |Photo |                                |with the |Milius   |
   |            |700   |  * 0 - Colour normal paper     |dumper   |         |
   |            |      |  * 1 - Colour photo paper      |         |         |
   |            |      |  * 2 - Grey normal paper       |         |         |
   |            |      |  * 3 - Grey photo paper        |         |         |
   |            |      |                                |         |         |
   |            |      |Available Text modes:           |         |         |
   |            |      |                                |         |         |
   |            |      |  * No highlights               |         |         |
   |            |      |  * Draft highlights            |         |         |
   |            |      |  * NLQ highlights              |         |         |
   |            |      |                                |         |         |
   |            |      |Pattern translation implemented.|         |         |
   |------------+------+--------------------------------+---------+---------|
   |            |      |  * 15 nozzles 6 colour mode.   |         |         |
   |            |Stylus|  * 15 nozzles Black mode.      |Supplied |         |
   |EPSON       |Photo |  * 360/360 dpi colour dithered |with the |Martin   |
   |            |870   |    Sprite output for preview   |dumper   |Hodgson  |
   |            |      |    purposes                    |         |         |
   |            |      |  * ???                         |         |         |
   +------------------------------------------------------------------------+

                                     Hints

   Only drivers which has been checked on the according printer are provided
   as PDF/calibration file with own name of the printer. For all other
   printers which may work with an existing driver but which has hasn't been
   checked in pratice there is entry with a link to an existing driver.

   Feel free to try an arbitrary driver for your printer. If it is successful
   please contact me so that I can update the list accordingly.

                                  Workarounds

   Technical development "proceeds". So things which have been easy in the
   good old times are becoming complicated today. A good example is the
   printing of pure text characters. In "good" old times only printing of
   text character in one size and one font was the only possibility of
   printing. Opposite to this today there are some printers which are only
   supporting graphics.

   If you are proud owner of such a printer model and need to print some
   texts you can help yourself with some tools. You can use text to PDF
   converters to convert your text file temporarily into a PDF file
   (Attention: the Adobe graphics format is meant) which afterwards can be
   printed in graphics mode. Converting is done quickly and the printing will
   lead to acceptable results too because usually only black and white is
   used.

3.2. Calibration

   If you are calibrating your printer you must determine the basic colours
   your printer is supporting. Each of such colours is coming from an ink
   cartridge fitted to your printer. The intensity of a basic colour printed
   to paper may be variied by the dumper by determing and sending it to the
   printer in accordance with the content of the document you are printing.
   The number of possible intensities is determined by the Bits per pixel
   shown inside a field of the calibration window. In the moment this value
   is 2 Bits for EPSON-Printers, but the value can be changed to 1 or 4. The
   dumper itself can cope with values between 1 and 8. An additional field
   allows to set the number of pad Bits. Usuallly this value will be 0. If
   you are choosing a different value this value is subtracted absolutely
   from the Bits per pixel. This means that this value reduces the number of
   intensities. You can use this field at printers which have e.g. 8
   intensities but are using 4 Bits to represent this values. In this case 1
   Bit of the colour value will be constant 0. If you choose a positive value
   for the pad Bits the most significant Bits are padded with 0. If you are
   choosing a negative value the less significant Bits are filled with 0
   which leads to a shift left of the value. Another field determines how the
   intensities of a basic colour are generated by default. You can choose
   between a logarithmic and a linear kind. Indepent of the intensity the
   general tone of a basic colour will stay. The basic colours can be mixed
   together and this will give you a fixed number of colours which can be
   printed. On this fact the whole dither concept of the dumper is based. For
   a given colour it tries to find the best approximation as a mixture of the
   really available colours. Which colours are really available you must tell
   the dumper during the next steps.

   Select the basic colours which are corresponding to the cartridges your
   printer is owning and then start the calibration process. Immediately
   afterwards a Draw-File will popup showing you a lot of rectangles. There
   is one line of rectangles per each selected cartridge. Inside the line the
   rectangles are having different intensities.

   Internally the calibration program has changed the calibration file to a
   special one which grants that every rectangle is printed exactly by ink
   from cartridge in undithered intensity determined by pixel intensity Bits.
   Print the draw files with the rectangles on your printer now.

   If looking on the printed results usually there will be a more or minor
   difference between the colours on the sheet of paper and that on the
   screen inside the Draw file. To cure this parallel with the Draw file a
   colour selection box will open showing you the colour of the uppermost
   left rectangle on your sheet of paper. You can change this colour now.
   After pressing the OK-Button (ATTENTION: Don't click Ok by mouse. At my
   Iyonix the actual entered value is not taken correctly) the next colour
   right to the last one will be displayed. After all intensities of a
   cartridge have been shown the next cartridge (one row of rectangles down
   on your sheet of paper) will be shown and so on until all colour on your
   sheet of paper have been calibrated. You can abort the calibation process
   by pressing the cancel button. In this case the calibration file used
   before is restored.

   You can try real printouts now. However It is likely that you have to
   recalibrate your printer again. Therefore some hints:

     * At black colours you are allowed to vary the intensity but not the
       tone of the colour. Keep RGB/CMY values all the same!

     * First try to get the right intensity for clear RGB/CMY colours and
       afterwards shift the tone.

     * You can use in principle green on red and so on. Of course this will
       lead to silly results.

     * Making usage of logarithmic kind of basic colour generation doesn't
       make sense from 8 or 16 intensities onwards. It decreases extremly
       fast towards pure white.

     * There is the problem how to obtain the best intensity of a basic
       printable colour at printers which are having more than one catridge
       for this colour (e.g. Cyan most Cyan). The calibration program adds
       all subtractive values. If one combination exceeds the usual colour
       cube the colour is modified in such a way that the values of the point
       just laying on a side of the cube and on a line between the calculated
       colour and the paper colour are taken. This point will be approximated
       by a mixture of the calculated colour and a certain amount of the
       paper colour. Inside the calibration mask there is a field "Intensity"
       where you can expand the intensity of all colours by a given factor
       beyond 100 percent. This will lead to reduced usage of the colours
       which might be helpful if too much ink is put on the paper (e.g. at
       interlaces).

   The calibration program is only one possibility to calibrate the printer.
   The important thing is the callibration file itself (ASCII-Format). You
   can edit it of course manually or generate it by an own program. So e.g.
   its is possible to calibrate every printable colour and not only the basic
   colours! One cartridge may e.g. have 2 intensities and another 16 and so
   on. However its is not simple to calculate the cubes around the colours.
   Therefore the possibility has been integrated to merge an external
   calibration file containing only colour, colour group and printer pattern
   information together with the colours generated by the calibration
   program. The name of the file must be entered inside the "Extern calib
   file" field. See "Extern calibration file" section for details.

   You can define up to 255 colour calibrations for one printer. This can be
   used for fine calibration in various modes and papers. Interlace-modes are
   putting more ink on the paper than non Interlace-modes. Colours are also
   looking different on usual papers and on photo paper. Using this feature
   you can calibrate the output as required. Note that the calibration can
   vary for each page if writing the according PDF.

   The calibrations can make usage of entirely different cartridges. This can
   used for setting up modes without using black cartridge or to simulate
   different cartridges as on the EPSON C80 using a special black mode.

   Inside the calibration mask there is a field "CalNum" where you can select
   one of the existing calibrations to modify it or to give it a new number.
   The next calibration process will affect the calibration belonging to the
   number entered in this field. Also you can remove one calibration pressing
   the button "delete calib".

                                 4. Motivation

   The printer dumper has been developed by myself during my USB stack
   development activities. I bought an EPSON 580 Stylus Color Printer at
   autumn 2001 to check my USB stack and had to make the expierence that none
   of the Printer Definition Files (PDF) supplied with RISC OS (<=4.02) could
   cope with it.

   So I decided to change this situation. I found out that it was not only
   the writing of a PDF file. The driver supplied for EPSON printers with
   RISC OS supported only an old kind of graphics generation. Unfortunately
   this mode requires that the numbers of black dots must match the number of
   colour dots. The 580 has two print heads with 48 dots for black and 3*15
   dots for Cyan, Magenta and Yellow. So you will not be able to find any
   combination which can be driven by RISC OS properly because the printer
   exspects 16 dots for black and 15 dots for the other colours in this mode.
   The printer offers a new mode that is not effected by this problem. This
   mode interpolates a given number of dots (15) onto the print head
   resolution internally inside the printer.

   So I wrote a new Printer Dumper to solve this problem. During the writing
   a lot of problems occurred. One of it was the correct adjustment of the
   colours. Another problem was to generate a good dithering. Together with
   this the problem occured to produce colour approximations inside the print
   which are having a certain similarity with the colours on your screen. The
   first attempt wasn't satisfying and allowed only usage of up to 4 colours
   so I had to revise the internal dithering concept entirely.

   I am not seeing the Dumper as a professional product or as a competition
   to professional printer drivers. It is only a help for all the frustrated
   RISC OS persons which are proud owners of printers which are not supported
   by RISC OS and where also no professional drivers are available, or where
   these drivers are not producing satisfying results. I am seeing this
   dumper more as an example to show how to write drivers under RISC OS.

                                  5. Copyright

   Copyright 2002-2004 by Thomas Milius Stade, Germany

   Source of the dumper is open source with some small restrictions to
   prevent commercial use without my agreement. I am allowed to use this code
   inside programs without publishing the code of this programs. These
   programs may be commercial. Other developers can use this source freely
   inside own software if the source code of this programs is made public to
   same conditions like valid to this code and no commercial profit is taken
   from the programs based on this code or must contact myself for my
   agreement of commercial usage.

                                   6. Contact

   If you are having questions, improvements or remarks don't hesitate to
   contact me:

   Thomas Milius
   Tilsiter Strasse 2
   21680 Stade
   Germany

   Telephone:
   04141/65005
   Work days from 19:00 until 21:30 and at weekends

   E-mail:
   Thomas-Milius@t-online.de

   Homepage:
   http://www.thomas-milius.homepage.t-online.de/indexE.htm

   An expert in inkjet printing which might help you with calibration or
   writing your own PDF is:

   Martin Hodgson

   E-mail:
   marthodgson@freeuk.com

                     7. Useful links for making an own PDF

   A documentation for the EPSON C40 which seems to have the same control
   sequences as the EPSON Stylus Color 580 can be found under:

   http://www.epsondevelopers.com/

   You must register yourself but free of charge (date March 2002). On this
   website you can also find some general documentation about EPSON control
   sequences and about EPSON Scanners.

   A little bit more restricted "to users with commercial interests" with
   manual check of your data on validity is the Canon developer page:

   http://www.developers.canon-europa.com/

   Another good source may be the GIMP-project which has been ported by
   Martin Wuerthner to RISC OS:

   http://www.gimp.org/

   Of course you will need the RISC OS Programmers Reference Manuals for
   understanding the RISC OS printing system. Important are also the printing
   system extensions documents.

                                   8. History

8.1. Version 1.00

   Release date:
     * 31.12.2002

   Price:
     * None because its open source and freeware

   Remarks:
     * First public version

   Corrected Bugs:
     * None

   New bugs/problems:
     * Colours could look better (but what can you do if Cyan is nearly blue
       and Magenta is also a little bit to much blue).
     * A little bit slow
     * Small but terrible bug inside Assembler/C-adapter causing memory
       corruption
     * Documentation error: Perform stack operation. POP and PUSH swapped

   New Features:
     * Monochrome printing
     * 8 Bit Greyscale printing
     * 32 Bit Colour printing
     * Resolution 360 * 360
     * Resolution 360 * 120 (poor results)

8.2. Version 1.01

   Release date:
     * 10.02.2003

   Price:
     * None because its open source and freeware

   Remarks:
     * Not published officially because I thougt it would takes take only two
       weeks more to release Version 2.00. Of course this delayed for years.
       So this version was sent directly to some frustrated people as a
       patch.

   Corrected Bugs:
     * Correct Assembler/C-adapter

   New bugs/problems:
     * None

   New Features:
     * None

8.3. Version 2.07

   Release date:
     * 30.09.2004

   Price:
     * None because its open source and freeware

   Remarks:
     * Entirely rewrite of dithering and some other parts
     * Dither information, calibration and PDF files are not backward
       compatible with version 1.x.. However PDF files will require only a
       small modifaction.

   Corrected Bugs:
     * Lots of various bugs/problems

   New bugs/problems:
     * Printing 8 Bit grey pictures from !Paint or !Photodesk in Grey mode
       will share the picture if printed vertically however.
     * Incorrect location under certain circumstances

   New Features:
     * Registered dumper module number
     * Colour calibration program
     * Installation by program
     * 8 Bit Colour printing
     * 16 Bit Colour printing
     * Direct output into Sprite file
     * Dithered output into Sprite file
     * Page size determination mode
     * Improved dithering and colour approximation
     * Support of up to 10 colour cartridges (limited by RISC OS internal up
       to 32 colour cartriges can be managed)
     * Support of arbitrary page sizes
     * Support of up to 255 print head nozzles
     * Support of arbitrary resolutions in vertical and horizontal direction
     * Support of up to 32 Bits per pixel printing information.
     * Support of up to 3 vertical interlaces
     * Support of an arbitrary number of cartridge print head stages.
     * Acceleration of simple Black/White printing even in colour modes.
     * Special grey dithering mode even in colour printing.
     * Using a dynamic area as dumper buffer.
     * RLL graphics output compression
     * several calibrations depending on mode/paper

                                   9. Future

   To do if required:

     * language specific error handling
     * filling of some environment variables
     * horizontal interlacing
     * 8 Bit Colour separation mode

                             10. Technical Details

   There are some remarks relating the drivers PDFs file and the computers
   where the dumper can be used etc..

   The dumper has been tested on my on my RiscPC (!Printers 1.64, RISC OS
   4.02), my RiscStation (!Printers 1.64, RISC OS 4.03) and on my IYONIX
   (!Printers 1.67, RISC OS 5.06).

   The Printer Dumper name and the number are registered. The dumper module
   number is 22 (&16).

   Number of vertical interlaces is indepent of dumper height. Dumper dept
   must always contain the number of nozzles on print head of each colour.
   Dumper height is a multiple of dumper dept and determines the stages of a
   print head. That means the arrangement of the colours on the head. E.g.
   the 580 has the cartridges Cyan, Yellow, Magenta and Black. Cyan is the
   top most printed colour. Afterwards Yellow and Black are located on the
   head. The last colour on the head is Magenta. This gives 3 stages. So
   dumper dept is 15. Dumper height is 3*15=45. Cyan is getting position 0 on
   print head (see ZERO_SKIP below), Yellow and Black are getting position 1,
   and Magenta gets the position 2.

   There is no fix relation of colours to LINE_START or LINE_PASS strings
   mentioned below. Each printer pixel is repesented by a certain amounts of
   Bits. The calibration contains the bit maps which are used to print a
   certain colour. These Bits maps are consisting of groups of 1,2 or more
   Bits for each cartridge. Each cartridge represents a basic colour which
   the printer can print in several intensities which number is determined by
   the Bits per pixel. If at least one bit of first Bit group is filled then
   LINE_START_1 sequence is sent (at 2 Bits Bits 0-1 of the bit map). If at
   least one bit of second Bit group is filled then LINE_PASS_1 sequence is
   sent (at 2 Bits Bits 2-3 of the bit map) and so on. That means
   colour/cartridge to string mapping is relating on the bit map
   representation of colours. To simplify the handling the calibration
   program is showing you an abbrevation of the related control sequence
   during the calibration. So usual LINE_START_1 will get sequence for Black
   and LINE_PASS_1 will get the sequence for Cyan. However this isn't the
   case if the printer has no Black cartridge. In that case LINE_START_1 will
   get Cyan and LINE_PASS_1 will get Yellow. I agree it is confusing but it
   is very flexible.

   The number of cartridges is determined by the highest used
   LINE_PASS/LINE_START string in the according mode.

   At the PDF only the following entries are used:

     * SET_LINES is containing the first part of the page start string
       because actual versions of !Printedit are only supporting 256 real
       printed signs which are much more than the real stored characters.
     * PAGE_START is containing the second part of the page start string.
       Both are merged internally together.
     * PAGE_END is containing the page end string.
     * LINE_RETURN may contain a RISC OS command which is executed by the
       dumper after the job has been finished. This can be used for various
       purposes like renaming the output file etc. Note that this sequence is
       evaluated inside all modes. So it can be used for sprites and usual
       print files. Cellar stack calculator can be used!
     * ZERO_SKIP is containing information about printer.

       +--------------------------------------------------------------------+
       | Byte |                           Meaning                           |
       |------+-------------------------------------------------------------|
       | 1    | Number of Bits used at printer for colour intensity         |
       |------+-------------------------------------------------------------|
       |      | Printer mode:                                               |
       |      |                                                             |
       |      | +---------------------------------------------------------+ |
       |      | | Mode number |                Description                | |
       |      | |-------------+-------------------------------------------| |
       |      | |             | Usual mode to generate sequences with     | |
       |      | | 0           | printer commands and dithered pixel data  | |
       |      | |             | to print a document.                      | |
       |      | |-------------+-------------------------------------------| |
       |      | |             | Generates only printer sequences but no   | |
       |      | | 1           | pixel data. Used for PDF developement and | |
       |      | |             | inside page size mode.                    | |
       |      | |-------------+-------------------------------------------| |
       |      | |             | Generates a 32 bit sprite file. Pixel     | |
       |      | |             | data is taken und dithered directly from  | |
       |      | | 2           | Printng system. Each page is a separate   | |
       |      | |             | sprite inside the file. Will only work    | |
       | 2    | |             | with a regular file as printer output     | |
       |      | |             | destination.                              | |
       |      | |-------------+-------------------------------------------| |
       |      | |             | Generates a 32 bit sprite file. Pixel     | |
       |      | |             | data is dithered with printer colours.    | |
       |      | | 3           | Each page is a separate sprite inside the | |
       |      | |             | file. Will only work with a regular file  | |
       |      | |             | as printer output destination. Used       | |
       |      | |             | heavily during Dumper Development.        | |
       |      | |-------------+-------------------------------------------| |
       |      | |             | Generates a pallete sprite file. Pixel    | |
       |      | |             | data is dithered with printer colours.    | |
       |      | |             | Each page is a separate sprite inside the | |
       |      | | 4           | file. Will only work with a regular file  | |
       |      | |             | as printer output destination. Number of  | |
       |      | |             | printer colours must not exceed 256 in    | |
       |      | |             | all combinations.                         | |
       |      | +---------------------------------------------------------+ |
       |------+-------------------------------------------------------------|
       |      | Position of a cartridge belonging to colour 1 at print      |
       |      | head. The upper most cartridge must have position 0. All    |
       | 3    | other cartridges must get accordingly their position 1, 2   |
       |      | and so on. Note that several cartridges may have the same   |
       |      | location if they are located on same level at print head.   |
       |      | Must be filled even colour is not used.                     |
       |------+-------------------------------------------------------------|
       | 4    | Position of a cartridge belonging to colour 2 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 5    | Position of a cartridge belonging to colour 3 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 6    | Position of a cartridge belonging to colour 4 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 7    | Position of a cartridge belonging to colour 5 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 8    | Position of a cartridge belonging to colour 6 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 9    | Position of a cartridge belonging to colour 7 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 10   | Position of a cartridge belonging to colour 8 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 11   | Position of a cartridge belonging to colour 9 at print      |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       | 12   | Position of a cartridge belonging to colour 10 at print     |
       |      | head.                                                       |
       |------+-------------------------------------------------------------|
       |      | Data compression mode:                                      |
       |      |                                                             |
       |      | +---------------------------------------------------------+ |
       |      | | Mode number |                Description                | |
       |      | |-------------+-------------------------------------------| |
       | 13   | | 0           | No compression. Data size equals bytes    | |
       |      | |             | sent.                                     | |
       |      | |-------------+-------------------------------------------| |
       |      | | 1           | Run length encoded (RLL) compression.     | |
       |      | |             | Data size equals bytes uncompressed.      | |
       |      | +---------------------------------------------------------+ |
       |------+-------------------------------------------------------------|
       |      | Number of the calibration which is used as default for      |
       | 14   | printing the job in this mode (can be variied for each page |
       |      | e.g. to take into account various paper types).             |
       +--------------------------------------------------------------------+

     * LINE_START_1 containes the string to pass graphics data for the first
       cartridge.
     * LINE_START_2 containes the string to pass graphics data for the sixth
       cartridge.
     * LINE_PASS_1 containes the string to pass graphics data for the second
       cartridge.
     * LINE_PASS_1b containes the string to pass graphics data for the
       seventh cartridge.
     * LINE_PASS_2 containes the string to pass graphics data for the third
       cartridge.
     * LINE_PASS_2b containes the string to pass graphics data for the eigth
       cartridge.
     * LINE_PASS_3 containes the string to pass graphics data for the fourth
       cartridge.
     * LINE_PASS_3b containes the string to pass graphics data for the nineth
       cartridge.
     * LINE_PASS_4 containes the string to pass graphics data for the fifth
       cartridge.
     * LINE_PASS_4b containes the string to pass graphics data for the tenth
       cartridge.
     * LINE_END_1 is containing the string to position the print head at the
       end of the line at first vertical interlace pass.
     * LINE_END_2 is containing the string to position the print head at the
       end of the line at second vertical interlace pass.
     * LINE_END_3 is containing the string to position the print head at the
       end of the line at third vertical interlace pass.

   All other strings are unused. Please note that the dumper provides a silly
   feature inside the strings, a so callled cellar stack calculator.

10.1. Printer control string cellar stack calculator

   The printer control string cellar stack calculator is an inversed polish
   notation calculator which control sequences are bytes inside a printer
   control string. A small calculator is called in such a case every time
   just before the control string is sent to the printer. During this
   evaluation all bytes belonging to the calculator sequence are removed from
   the string. Instead the calculator can generate a new sequence of bytes
   which is sent to the printer.

   The purpose of such a calculator is to generate strings dynamically from
   internal states of the dumper and also to set some states of the dumper.
   E.g. the size of data no longer depends on a part before or behind a
   certain sequence and causes neeed of a new printer dumper only because
   manufacturer A prefers little endian coded size while manufacturer B
   prefers big endian coded size.

   The calculator is activated by a byte of value 0xFF inside a control
   string. This byte belongs to the calculator sequence and is removed from
   the string control sequence. A byte of 0xFF also ends a calculator
   sequence (the calculation may be ended by another sequence conditionally
   earlier). Because a sequence of 0xFF 0xFF really makes no sense (start
   calculator, end calculator) it is replaced by a single 0xFF inside the
   string control sequence.

   Note that a string control sequence can contain several indepedent
   calculator sequences.

   The cellar stack machine itself consists of 4 stack registers (A, B, C,
   D), a condition flag to allow conditional operations and a couple of
   variables. The content of the variables is determined either by the dumper
   itself or by the actions done on them by the calculator. When a cellar
   stack sequence starts the condition is FALSE and the state of the stack
   registers is indetermined. The state of the variables not owned by the
   dumper itself is indetermined at start of a printer job.

   Each command is 1 Byte long. Bits are numbered from 0 to 7. Bit 7 shows
   whether a command must be always executed (=1) or only if the condition
   state is TRUE (=0).

   You can control the execution of cellar stack sequences by typing the
   command:

 TraceCellarStack on

   This will write a trace protocol of the sequences into your output file
   which can't be printed then. You can switch trace off by typing the
   command:

 TraceCellarStack off

   The actual trace state can be viewn by typing the command:

 TraceCellarStack

  10.1.1. Commands

 C000XXXX - Load nibble.
            XXXX gives nibble value which is loaded onto the stack (register A).
            Stack is pushed before.

 C001XXXX - Set Condition.
            XXXX gives the check which is performed:
            0000 - A = 0
            0001 - A != 0
            0010 - A < 0
            0011 - A > 0
            0100 - A <= 0
            0101 - A >= 0
            0110 - Condition set to FALSE
            0111 - Condition set to TRUE
            1000 - A = B pop registers
            1001 - A != B pop registers
            1010 - A < B pop registers
            1011 - A > B pop registers
            1100 - A <= B pop registers
            1101 - A >= B pop registers
            1110 - Invert Condition
            1111 - reserved

 C010XXXX - Perform stack operation.
            XXXX gives the operation which is performed:
            0000 - B + A
            0001 - B - A
            0010 - B * A
            0011 - B / A
            0100 - B MOD A
            0101 - B POWER A
            0110 - B shifted right by A
            0111 - B shifted left by A
            1000 - INVERT A
            1001 - B OR A
            1010 - B AND A
            1011 - B EXOR A
            1100 - POP Stack (A will be dropped)
            1101 - PUSH Stack (A will be doubled)
            1110 - SWAP A B
            1111 - (B << 4) OR (A AND 0x0000000F). Useful for loading arbitrary values by Nibbles

            The operands are usually dropped from stack that means the stack will be popped acordingly
            and the result will pushed on the stack.

 C0110XXX - Write stack content register A into control sequence.
            Stack is popped afterwards.
            XXX gives the format of the output:
            000 - As humanreadable decimal number digits (0-9)
            001 - 1 Byte binary number
            100 - As humanreadable hexadecimal number lower case letters (0-9, a-f)
            101 - As humanreadable hexadecimal number upper case letters (0-9, A-F)

            and

             10 - 2 Bytes binary number
             11 - 4 Bytes binary number

            with

            0   - little endian
            1   - big endian

 C01110XX - Compare page size (width/height according variables
            0x00000018 and 0x00000019) with page size sequences
            inside the page sequence configuration table. If
            a matching entry is found then the condition is set to TRUE
            and the sequence determined by XX (0-3) is depending
            on its type (see below) either put it into the
            output sequence or its value is pushed on the stack.
            If no matching is found then set the condition
            to FALSE.

            Inside the configuration file you can include
            page sequences in the following way:
            "page_sequence_start" shows the beginning of
            the sequence list. "page_sequence_end" terminates
            the sequence list. Between them there can be an
            arbitrary number of page sequences of the following
            format:

            decimal_page_width deciaml_page_height [sequence_0 [sequence_1 [sequence_2 [sequence_3]]]]

            A sequence consists of an identifier followed by a colon:

            - V: shows a value which is pushed onto the stack followed by the decimal value

            - S: shows a control sequence which is inserted into the printer control
              sequence. The sequence has the usual form of control strings used inside print
              edit (mixture of quoted letters and decimal numbers separated by commas, no
              cellar stack sequences are allowed in here, so 255 means really the letter 255).
              Important: No space is allowed inside the sequence as it would show the
              beginning of the next sequence.

            Note that sequence may be optionally given and S: and V: sequences can be mixed
            arbitrarily. Example:

            12345 456789 S:27,"(","C",4,0,"q",16,0,0 V:123,456

            sequence 0 for page size 12345/456789 is 27,"(","C",4,0,"q",16,0,0 and
            will be inserted into the print control sequence.

            sequence 1 gives values of 123 and 456 which will be pushed on the stack.
            123 will be pushed first onto the stack and 456 will be pushed afterwards
            onto the stack. So register B will contain 123 and register A will contain 456.

            sequence 2 and sequence 3 are not defined.

            What can you do with such a sequence:

            a. you can tell the printer the paper size (A4, letter)
            b. you can tell the printer the paper source
            c. you can tell the printer the paper type (photo/normal)

            Note: Use a trick to handle special paper types. Due to the
            absence of another possibility inside RISC OS to tell
            the paper type simply use a slightly smaller width or high
            than of normal paper. This won't influence the printing
            process.

 C0111110 - Save stack content B into variable which is determined by A.
            Stack is popped afterwards (A is dropped).

 C0111111 - Load stack with content of a variable which is determined by A.
            A is replaced by the content of the variable.

 C100XXXX - Load stack with content of a job state variable.
            Stack is pushed before.
            XXXX gives the address of the job state variable.

 C10100XX - Write name of target file into control sequence.
            No Stack operation is performed.

            XX gives the format of the output:
            00 - reserved
            01 - file name
            10 - path
            11 - path and file name

 01010100 - Write a sequence of bytes following this command into
            control sequence conditionally. The sequence is terminated
            by 11010100 which doesn't make other sense for it would
            have the same meaning as locating the same data outside a
            cellar stack sequence. A byte 11010100 inside the sequence
            can be represented by two 11010100 following after eachother.
            According to the condition the sequence is written or ignored.
            In both cases the cellar stack calculator continues with the
            command after the terminating 11010100. You can embed 11111111
            inside the sequence. It is not treatened as a cellar stack
            terminator.

 11010100 - Terminates a sequence of bytes introduced by 01010100. A
            11010100 without a 01010100 has no effect.

 11111111 - End of cellar stack sequence. The command pointer will point beyond it at end of
            cellar stack execution. This sequence is mandatory. If it is not existing
            the whole stack evaluation except changing of the variables will be ignored.

 01111111 - Conditional end of cellar stack sequence. Execution stops here but sequence is skipped
            until 0xFF is found.


   All other sequences are reserved.

  10.1.2. Addresses of Variables

   From 0x00000000 to 0x0000000F there are variables which are manipulated
   during runtime of the job by the dumper (read only)

 0x00000000 - Number of remaining copies
 0x00000001 - Number of actual stage (updated before each data output)
 0x00000002 - Number of actual vertical interlace (updated before each data output)
 0x00000003 - Number of actual horizontal interlace (updated before each data output)
 0x00000004 - Bytes of all data sent in the next data block (updated before each data output).
 0x00000005 - Bytes per line filled (updated before each data output).
              Excluding blank parts on the right side. Attention: This are bytes not pixel.
 0x00000006 - Number actual page of job
 0x00000007 - Number of the job since start of the dumper for unique identification
              purposes.
 0x00000008 - 0x0000000F reserved

   From 0x00000010 to 0x0000004F there are variables which are determined by
   the printing system (read only)

 0x00000010 - Total number of vertical interlaces
 0x00000011 - Total number of horizontal interlaces
 0x00000012 - Total number of colours (Not implemented yet)
 0x00000013 - Total number of dots per print head
 0x00000014 - vertical dots per inch
 0x00000015 - horizontal dots per inch
 0x00000016 - vertical offset in pixel at beginning of the page
 0x00000017 - horizontal left side offset in pixel at beginning of the line
 0x00000018 - page width in inch/10000
 0x00000019 - page height in inch/10000
 0x0000001A - page range top left vertical position in inch/10000
 0x0000001B - page range top left horizontal position in inch/10000
 0x0000001C - page range bottom right vertical position in inch/10000
 0x0000001D - page range bottom right horizontal position in inch/10000
 0x0000001E - 0x0000004F reserved

   From 0x00000050 to 0x0000007F there are variables which are determining
   the dumper behaviour (read/write depending on variable):

 0x00000050 - Total number of stages (read only)
 0x00000051 - data compression format (read/write)
 0x00000052 - vertical offset in pixel at beginning of the page not handled by control sequences (read/write).
              Automatically updated at start of every page. It makes only sense to change it at the
              page start sequence
 0x00000053 - Remaining copies of page (read/write)
              Automatically updated at start of every page.
 0x00000054 - number of printer cartridges (read only)
 0x00000055 - Bits per printer pixel (read only)
 0x00000056 - Printer Mode (read only)
 0x00000057 - Calibration (read/write)
              Initialized with Byte 14 of ZERO_SKIP.
              Can be changed for every page depending on the type
              of paper.
 0x00000058 - 0x0000007F reserved

   From 0x00000080 to 0x000000FF there are variables free for program usage.
   They are uninitialized at beginning of print job but are kept until the
   end of the print job (read/write):

 0x00000080 - 0x0000008F free useable variables
 0x00000090 - 0x000000FF reserved

  10.1.3. Programming example

   To clarify programming the example below shows how to implement a vertical
   form feed counter for sequence optimation.

   +------------------------------------------------------------------------+
   | Binary   | Decimal | Reg A | Reg B | Reg C | Reg D | Comments          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Initialisation    |
   |          |         |       |       |       |       | sequence          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 11111111 | 255     |       |       |       |       | Start             |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Clear feed        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Load value 0 for  |
   | 10000000 | 128     | 0     |       |       |       | transfer to       |
   |          |         |       |       |       |       | variable          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Number of         |
   | 10001000 | 136     | 8     | 0     |       |       | variable high     |
   |          |         |       |       |       |       | Nibble (8)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Number of         |
   | 10000000 | 128     | 0     | 8     | 0     |       | variable low      |
   |          |         |       |       |       |       | Nibble (0)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10101111 | 175     | 0x80  | 0     |       |       | Build address of  |
   |          |         |       |       |       |       | variable (0x80)   |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10111110 | 190     | 0     |       |       |       | Store value into  |
   |          |         |       |       |       |       | variable          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 11111111 | 255     |       |       |       |       | End               |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Line End Sequence |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 11111111 | 255     |       |       |       |       | Start             |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Cumulate feed     |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Load old feed     |
   |          |         |       |       |       |       | value             |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Number of         |
   | 10001000 | 136     | 0x08  |       |       |       | variable high     |
   |          |         |       |       |       |       | Nibble (8)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Number of         |
   | 10000000 | 128     | 0x00  | 0x08  |       |       | variable low      |
   |          |         |       |       |       |       | Nibble (0)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10101111 | 175     | 0x80  |       |       |       | Build address of  |
   |          |         |       |       |       |       | variable (0x80)   |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Duplicate number  |
   | 10101101 | 173     | 0x80  | 0x80  |       |       | for restoring the |
   |          |         |       |       |       |       | value later       |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10111111 | 191     | e.g.  | 0x80  |       |       | Load value from   |
   |          |         | 0     |       |       |       | variable          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Feed after this   |
   |          |         |       |       |       |       | line              |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10000001 | 129     | 0x01  | e.g.  | 0x80  |       | Feed value high   |
   |          |         |       | 0     |       |       | Nibble (1)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10000001 | 129     | 0x01  | 0x01  | e.g.  | 0x80  | Feed value low    |
   |          |         |       |       | 0     |       | Nibble (1)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10101111 | 175     | 0x11  | e.g.  | 0x80  |       | Build feed value  |
   |          |         |       | 0     |       |       | (0x11)            |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Increase feed     |
   |          |         |       |       |       |       | value             |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         | e.g.  |       |       |       | Addition of old   |
   | 10100000 | 160     | 0x11  | 0x80  |       |       | and new value at  |
   |          |         |       |       |       |       | top of stack      |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Store feed value  |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       | e.g.  |       |       | Swap number of    |
   | 10101110 | 174     | 0x80  | 0x11  |       |       | variable and      |
   |          |         |       |       |       |       | value on stack    |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10111110 | 190     | e.g.  |       |       |       | Store value into  |
   |          |         | 0x11  |       |       |       | variable          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 11111111 | 255     |       |       |       |       | End               |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Data sequence     |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | It is assumed     |
   |          |         |       |       |       |       | that the feed     |
   |          |         |       |       |       |       | sequence is       |
   |          |         |       |       |       |       | inside the        |
   |          |         |       |       |       |       | control sequence  |
   |          |         |       |       |       |       | already and that  |
   |          |         |       |       |       |       | at here only the  |
   |          |         |       |       |       |       | feed value must   |
   |          |         |       |       |       |       | be filled         |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 11111111 | 255     |       |       |       |       | Start             |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Put feed into     |
   |          |         |       |       |       |       | sequence          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Number of         |
   | 10001000 | 136     | 8     |       |       |       | variable high     |
   |          |         |       |       |       |       | Nibble (8)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Number of         |
   | 10000000 | 128     | 0     | 8     |       |       | variable low      |
   |          |         |       |       |       |       | Nibble (0)        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10101111 | 175     | 0x80  |       |       |       | Build address of  |
   |          |         |       |       |       |       | variable (0x80)   |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Duplicate number  |
   | 10101101 | 173     | 0x80  | 0x80  |       |       | for clearing the  |
   |          |         |       |       |       |       | value later       |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10111111 | 191     | e.g.  | 0x80  |       |       | Load value from   |
   |          |         | 0x11  |       |       |       | variable          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Put value as 4    |
   | 10110111 | 183     | 0x80  |       |       |       | byte binary big   |
   |          |         |       |       |       |       | endian into the   |
   |          |         |       |       |       |       | control sequence  |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Clear Feed        |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Load value 0 for  |
   | 10000000 | 128     | 0     | 0x80  |       |       | transfer to       |
   |          |         |       |       |       |       | variable          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Store feed value  |
   |----------+---------+-------+-------+-------+-------+-------------------|
   |          |         |       |       |       |       | Swap number of    |
   | 10101110 | 174     | 0x80  | 0     |       |       | variable and      |
   |          |         |       |       |       |       | value on stack    |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 10111110 | 190     | 0     |       |       |       | Store value into  |
   |          |         |       |       |       |       | variable          |
   |----------+---------+-------+-------+-------+-------+-------------------|
   | 11111111 | 255     |       |       |       |       | End               |
   +------------------------------------------------------------------------+

10.2. Printer individual calibration file

   The files are named in the same way as the printer they are used for and
   are located inside <Printers$Dir>.Resources.PDumpers.PDumperEI directory.
   They are usually manipulated by the configuration program but can be also
   maintained manually. A set of entirely calibrated files can be found under
   <PDPEICal$Dir>.Resources.Calibs. A basical default file is
   <PDPEICal$Dir>.Resources.CalibDef which contains no colour definition. The
   calibration program first tries to take the actual settings for the
   printer, if this not exists it searches inside Calibs directory.

   The individual printer calibration files are consisting of comment lines
   introduced by a "#" or printer individual settings. The lines may be up to
   511 Bytes long. The printer settings are divided into settings groups.
   Each group is introduced by a line which contains the start tag of a group
   (optionally followed by parameters). Then the lines containing various
   settings are following in special format which depends on the group. At
   the end there is always a line containing an end tag of the the group.
   Empty lines are not allowed. Comment lines can be located at arbitrary
   places. There are the following setting groups:

    1. printer head adjustment
    2. page handling
    3. colour calibration

+------------------------------------------------------------------------------+
|                                Setting group                                 |
|------------------------------------------------------------------------------|
|              start tag               |                end tag                |
|------------------------------------------------------------------------------|
|    Position     |                          meaning                           |
|------------------------------------------------------------------------------|
|                           printer head adjustment                            |
|------------------------------------------------------------------------------|
| head_adjustment_start                | head_adjustment_end                   |
|------------------------------------------------------------------------------|
| 1               | "v" or "h" for vertical or horizontal                      |
|-----------------+------------------------------------------------------------|
| 2               | cartridge (0-9)                                            |
|-----------------+------------------------------------------------------------|
| 3               | Adjustment in pixel as Integer (at horizontal only         |
|                 | positive values are allowed)                               |
|------------------------------------------------------------------------------|
|                                page handling                                 |
|------------------------------------------------------------------------------|
| page_sequence_start                  | page_sequence_end                     |
|------------------------------------------------------------------------------|
|                 | page width in inch/10000 (decimal)                         |
|                 |                                                            |
| 1               | Important note: Due to internal rounding differences Paper |
|                 | sizes between DIN AX and DIN AX Generic may vary. Use      |
|                 | "Dummy for page size" Printer mode with an empty sheet of  |
|                 | paper to determine the correct sizes                       |
|-----------------+------------------------------------------------------------|
| 2               | page height in inch/10000 (decimal)                        |
|-----------------+------------------------------------------------------------|
|                 | sequence 0 (optional).                                     |
|                 |                                                            |
|                 | A sequence is introduced by a type tag "S:" or "V:". "S:"  |
|                 | is followed by a printer control sequence in the same form |
|                 | as inside print edit but without cellar stack so that 255  |
| 3               | means really character 255. Spaces are not allowed inside  |
|                 | such a sequence (use 32 instead) "V:" is followed by up to |
|                 | 4 comma separated decimal integer values                   |
|                 |                                                            |
|                 | All this sequences are only making sense if they are       |
|                 | referenced accordingly inside cellar stack sequences       |
|-----------------+------------------------------------------------------------|
| 4               | sequence 1 (optional only if sequence 0 is given).         |
|-----------------+------------------------------------------------------------|
| 5               | sequence 2 (optional only if sequence 1 is given).         |
|-----------------+------------------------------------------------------------|
| 6               | sequence 3 (optional only if sequence 2 is given).         |
|------------------------------------------------------------------------------|
|                              colour calibration                              |
|------------------------------------------------------------------------------|
| printable_colours_start              | printable_colours_end                 |
| [Reference_Number]                   |                                       |
|------------------------------------------------------------------------------|
| 1               | Red component of printable colour (decimal 0-255)          |
|-----------------+------------------------------------------------------------|
| 2               | Green component of printable colour (decimal 0-255)        |
|-----------------+------------------------------------------------------------|
| 3               | Blue component of printable colour (decimal 0-255)         |
|-----------------+------------------------------------------------------------|
| 4               | minimal Red component covered by this colour (decimal      |
|                 | 0-255)                                                     |
|-----------------+------------------------------------------------------------|
| 5               | maximal Red component covered by this colour (decimal      |
|                 | 0-255)                                                     |
|-----------------+------------------------------------------------------------|
| 6               | minimal Green component covered by this colour (decimal    |
|                 | 0-255)                                                     |
|-----------------+------------------------------------------------------------|
| 7               | maximal Green component covered by this colour (decimal    |
|                 | 0-255)                                                     |
|-----------------+------------------------------------------------------------|
| 8               | mininal Blue component covered by this colour (decimal     |
|                 | 0-255)                                                     |
|-----------------+------------------------------------------------------------|
| 9               | maximal Blue component covered by this colour (decimal     |
|                 | 0-255)                                                     |
|-----------------+------------------------------------------------------------|
|                 | Printer pattern to generate the colour (hexadecimal up to  |
| 10              | 32 Bit). Depending on Bits per pixel and number of         |
|                 | cartridges and required printer pixel colour intensity     |
|                 | format.                                                    |
|-----------------+------------------------------------------------------------|
|                 | Colour Group mask (hexadecimal).                           |
|                 |                                                            |
|                 | +--------------------------------------------------------+ |
|                 | | Bit |                     Meaning                      | |
|                 | |-----+--------------------------------------------------| |
|                 | |     | Paper colour. Member of no other group.          | |
|                 | | 0   | Necassary for acceleration and used as default   | |
|                 | |     | if no other colours found.                       | |
|                 | |-----+--------------------------------------------------| |
|                 | |     | Pure black. Usually but not necassary member     | |
|                 | | 1   | inside black group. Necassary for Black/White    | |
|                 | |     | acceleration.                                    | |
|                 | |-----+--------------------------------------------------| |
|                 | | 2   | Black group. Necessary for Black/White           | |
|                 | |     | dithering.                                       | |
|                 | |-----+--------------------------------------------------| |
| 11              | | 3   | Cyan group. Also member inside CMY and colour    | |
|                 | |     | group. Necassary to determine Cyan colours.      | |
|                 | |-----+--------------------------------------------------| |
|                 | | 4   | Magenta group. Also member inside CMY and colour | |
|                 | |     | group. Necassary to determine Magenta colours.   | |
|                 | |-----+--------------------------------------------------| |
|                 | | 5   | Yellow group. Also member inside CMY and colour  | |
|                 | |     | group. Necassary to determine Yellow colours.    | |
|                 | |-----+--------------------------------------------------| |
|                 | | 6   | CMY colour group. Also member of colour group.   | |
|                 | |     | Not needed internally in the moment.             | |
|                 | |-----+--------------------------------------------------| |
|                 | | 7   | Hexachrome Colour group. Also member of colour   | |
|                 | |     | group. Not needed internally in the moment.      | |
|                 | |-----+--------------------------------------------------| |
|                 | | 8   | Colour group. Needed as dither information.      | |
|                 | +--------------------------------------------------------+ |
|-----------------+------------------------------------------------------------|
|                 | Percentage of paper colour required if displaying this     |
|                 | colour. Usually 0. Maximum 99. This value is used if too   |
|                 | much subtraction colours are overlayed drinking the paper  |
|                 | in ink. The value is calculated by generating a line from  |
|                 | the point with components values smaller than 0 in RGB     |
| 12              | cube to paper colour. Where the line goes trough a side of |
|                 | the RGB-cube there is the point giving the colour          |
|                 | components stored inside this line. This value is          |
|                 | calulated as length of line between stored point and       |
|                 | original point divided by length between paper colour and  |
|                 | original point.                                            |
+------------------------------------------------------------------------------+

  10.2.1. The "Dummy for page size" mode

   The "Dummy for page size" mode is a special printing mode which allows you
   easily to determine the width and height values for your own page sizes.

    1. Select "Dummy for page size" mode
    2. Select an arbitrary file for output for your EPSON Stylus Color 580
       Printer
    3. Open an empty sheet of paper in an arbitrary application where you can
       print it (e.g. !Writer)
    4. Print the empty sheet
    5. Look into your Printout-Output-File. You will find a line with two
       values.
    6. Copy this line into your printer individual calibration file inside
       the page handling group.
    7. Add the according "S:"-page sequence to the just added line.
    8. Set the printer back to its usual output and a usual resolution.

10.3 External calibration file

   You can import colour defintions from an external file. This is merged
   with the colours generated by !PDPEICal. Merge takes places after
   generation of the colours from the calibrated basic colours. If no
   catridges have been selected at least paper colour will be generated
   internally. This is the usual way to include the external calibration
   file. The additonal colours are imported from the calibration file which
   contains RGB components, paper colour fraction, printer pattern, colour
   group information. The additional colours are checked for duplicates
   against that colours generated already by !PDPEICal. The additonal colours
   are having a higher priority and will be kept instead of that from
   !PDPEICal. The external calibration file must not contain a definition for
   the paper colour.

+------------------------------------------------------------------------------+
| Column |                               Content                               |
|--------+---------------------------------------------------------------------|
| 1      | Red component of printable colour (decimal 0-255)                   |
|--------+---------------------------------------------------------------------|
| 2      | Green component of printable colour (decimal 0-255)                 |
|--------+---------------------------------------------------------------------|
| 3      | Blue component of printable colour (decimal 0-255)                  |
|--------+---------------------------------------------------------------------|
|        | Printer pattern to generate the colour (hexadecimal up to 32 Bit).  |
| 4      | Depending on Bits per pixel and number of cartridges and required   |
|        | printer pixel colour intensity format.                              |
|--------+---------------------------------------------------------------------|
| 5      | Colour group mask (hexadecimal)                                     |
|--------+---------------------------------------------------------------------|
| 6      | Percentage of paper colour required if displaying this colour       |
+------------------------------------------------------------------------------+

10.4. Ditherinfo file

   The ditherinfo file is located at
   <Printers$Dir>.Resources.PDumpers.PDumperEI. It contains the horizontal
   offset information for each line used by dithering.

           +--------------------------------------------------------+
           | Column |                    Content                    |
           |--------+-----------------------------------------------|
           | 1      | Constant "ho" for horizontal offset           |
           |--------+-----------------------------------------------|
           | 2      | line number at which the offset shall be used |
           |--------+-----------------------------------------------|
           | 3      | occurance at which the offset shall be used   |
           |--------+-----------------------------------------------|
           | 4      | offset in pixels                              |
           +--------------------------------------------------------+

   Inside <PDPEICal$Dir>.Resources there is a small BASIC program called
   GenDither which generates a Ditherinfo file if the actual one should not
   be satisfying.
